@yaebal/rich 0.0.1 → 0.0.3

package/README.md

@@ -1,8 +1,8 @@
 # @yaebal/rich
 
-`sendRichMessage` / `sendRichMessageDraft` — telegram's block-tree message format. a typed builder for the extended html dialect, a draft/streaming session that owns the 30s ttl, and full read-side coverage (type guards + plain-text flattening) of everything telegram can hand back on `message.rich_message`.
+`sendRichMessage` / `sendRichMessageDraft` — telegram's block-tree message format. one dual-dialect builder set, a draft/streaming session that owns the 30s ttl, and full read-side coverage (type guards + plain-text flattening) of everything telegram can hand back on `message.rich_message`.
 
-unlike classic `parse_mode`/entities (see [`@yaebal/fmt`](https://www.npmjs.com/package/@yaebal/fmt)), a rich message isn't a flat `{ text, entities }` pair — it's a document: paragraphs, headings, tables, lists, collages, slideshows, block quotes, a collapsible `<details>`, even a `<tg-thinking>` placeholder for streaming an in-progress answer. you write extended html (or markdown), telegram parses it server-side into a `RichMessage.blocks` tree, and that same tree is what you read back.
+unlike classic `parse_mode`/entities (see [`@yaebal/fmt`](https://npmx.dev/package/@yaebal/fmt)), a rich message isn't a flat `{ text, entities }` pair — it's a document: paragraphs, headings, tables, lists, collages, slideshows, block quotes, a collapsible `<details>`, even a `<tg-thinking>` placeholder for streaming an in-progress answer. you write extended html (or markdown), telegram parses it server-side into a `RichMessage.blocks` tree, and that same tree is what you read back.
 
 ## install
 
@@ -10,54 +10,109 @@ unlike classic `parse_mode`/entities (see [`@yaebal/fmt`](https://www.npmjs.com/
 pnpm add @yaebal/rich
 ```
 
-## sending
+## one builder, two dialects
+
+telegram accepts a rich message as either `InputRichMessage.html` or `.markdown`. most rich-message libraries pick one dialect to build for and bolt the other on as a parallel, hand-duplicated set of functions. `@yaebal/rich` doesn't: every builder — `bold`, `paragraph`, `table`, `list`, all ~40 of them — returns a `RichNode` that doesn't know its own output format yet. it renders itself only when it lands inside a template:
+
+```ts
+import { html, md, heading, paragraph, bold, link, sendRichMessage } from "@yaebal/rich";
+
+const title = "release notes";
+const body = [
+  heading(1, title),
+  paragraph("yaebal ", bold("0.1"), " is out — see ", link("https://yaebal.pages.dev", "the docs"), "."),
+];
+
+await sendRichMessage(ctx.api, ctx.chat.id, html(body)); // <h1>…</h1><p>…</p>
+await sendRichMessage(ctx.api, ctx.chat.id, md(body));   // # …\n\n…
+```
+
+there is no `md.bold`/`md.paragraph` shadow api to learn, nothing to keep in sync, and nothing that silently drifts between dialects — `bold(...)` is `bold(...)` everywhere. `html`/`md` are tagged templates first:
 
 ```ts
-import { document, heading, paragraph, bold, link, sendRichMessage } from "@yaebal/rich";
+const doc = html`
+  ${heading(1, title)}
 
-const input = document([
-  heading(1, "release notes"),
-  paragraph("yaebal ", bold("0.1"), " is out — see ", link("https://yaeb.al", "the docs"), "."),
-]);
+  ${paragraph("yaebal ", bold("0.1"), " is out — see ", link("https://yaebal.pages.dev", "the docs"), ".")}
+`;
 
-await sendRichMessage(ctx.api, ctx.chat.id, input);
+await sendRichMessage(ctx.api, ctx.chat.id, doc);
 ```
 
-or install the plugin for `ctx.send`-flavored ergonomics:
+literal template text passes through unchanged; only `${…}` interpolation is touched:
+
+| interpolation                           | what happens                                                       |
+|:----------------------------------------|:-------------------------------------------------------------------|
+| `${string}` / `${number}` / `${bigint}` | dialect-escaped — renders literally, can't inject formatting       |
+| `${builderNode}`                        | rendered into the template's dialect                               |
+| `${anotherDocument}`                    | inlined as-is if dialects match, throws `RichError` if they don't  |
+| `${array}`                              | each item rendered and concatenated                                |
+| `${null \| undefined \| false}`         | empty string — so `cond && bold("x")` composes cleanly             |
+
+multi-line templates are **dedented** (common leading indentation stripped) so you can write at your code's natural indent level. `html`/`md` also accept a plain string (passed through as-is, no escaping/dedent — for already-formatted content) or an array of blocks (each rendered and, for markdown, blank-line-joined — the form to reach for when composing from data instead of prose):
+
+```ts
+html([heading(1, title), list(items.map((i) => paragraph(i.text)))]);
+```
+
+`document(blocks, { dialect, rtl, skipEntityDetection })` is the options-object equivalent of `html(blocks)`/`md(blocks)`, for when the dialect is a runtime variable rather than a call-site choice.
+
+### `RichDocument` — the sendable result
+
+`html`/`md`/`document()` all return a `RichDocument`: a rendered string plus the `InputRichMessage` flags, settable fluently.
+
+```ts
+const doc = html`${paragraph("right-to-left, no auto-linking")}`
+  .rtl()
+  .noEntityDetection();
+
+await sendRichMessage(ctx.api, ctx.chat.id, doc);
+```
+
+`sendRichMessage`/`sendRichMessageDraft`/`RichMessageDraft` all accept a `RichDocument`, a raw `InputRichMessage`, or a plain html string interchangeably — `toJSON()` also delegates to `toInputRichMessage()`, so a `RichDocument` serializes correctly even nested inside a hand-built payload.
+
+### install the plugin for `ctx.send`-flavored ergonomics
 
 ```ts
 import { Bot } from "@yaebal/core";
-import { rich, document, paragraph } from "@yaebal/rich";
+import { rich, html, paragraph } from "@yaebal/rich";
 
 const bot = new Bot(token)
   .install(rich())
-  .command("hi", (ctx) => ctx.sendRichMessage(document([paragraph("hello!")])));
+  .command("hi", (ctx) => ctx.sendRichMessage(html`${paragraph("hello!")}`));
 ```
 
 ## streaming a draft
 
 `sendRichMessageDraft` streams a partial answer to a private chat — but the draft is **ephemeral**: telegram drops it 30 seconds after the last push, and it never becomes a real message on its own. `RichMessageDraft` owns that lifecycle: it re-pushes the latest draft on a timer so a slow generator doesn't lose it, and it refuses to push after you close it.
 
+two ways to grow a draft: `rewrite()` replaces the whole thing — right for a token stream, where every chunk is a longer version of the *same* paragraph. `write()` appends to it (plain string concatenation) — right for tacking on a block after content that's already there, without re-supplying it.
+
 ```ts
-import { thinking, document, paragraph, sendRichMessage } from "@yaebal/rich";
+import { thinking, html, paragraph, divider, footer } from "@yaebal/rich";
 
 bot.command("ask", async (ctx) => {
   const draft = ctx.richMessageDraft(1); // draft_id, non-zero, per-message
 
-  await draft.push(thinking("thinking…")); // draft-only block, see below
+  await draft.rewrite(html`${thinking("thinking…")}`); // draft-only block, see below
 
   let text = "";
   for await (const chunk of streamAnswer(ctx.text)) {
     text += chunk;
-    await draft.push(document([paragraph(text)]));
+    await draft.rewrite(html`${paragraph(text)}`);
   }
 
-  // required: a draft never persists on its own.
-  await draft.commit(document([paragraph(text)]));
+  await draft.write(html`${divider()}${footer("streamed")}`); // append, no need to re-supply `text`
+
+  // required: a draft never persists on its own. send() with no argument
+  // auto-assembles from the rewrite()/write() calls above; pass an explicit
+  // override (as here) when the persisted message should differ from the last
+  // draft snapshot.
+  await draft.send(html`${paragraph(text.trim())}${divider()}${footer("streamed")}`);
 });
 ```
 
-call `draft.cancel()` instead of `commit()` to abandon a draft without persisting anything (it expires within 30s regardless).
+call `draft.cancel()` instead of `send()` to abandon a draft without persisting anything (it expires within 30s regardless).
 
 ## reading
 
@@ -76,31 +131,50 @@ bot.on("message:rich_message", (ctx) => {
 
 every one of telegram's ~50 `Rich*` types is covered on both sides:
 
-- **write** — a builder function (or documented auto-detection) for every block and inline mark.
+- **write** — a builder function (or documented auto-detection) for every block and inline mark, in both dialects at once.
 - **read** — an `isX` type guard and a plain-text flattening branch for every block and inline mark.
 
-most tags are **confirmed** directly from telegram's schema (`<p>`, `<h1>`–`<h6>`, `<pre><code>`, `<hr/>`, `<footer>`, `<blockquote>`, `<aside>` for pull-quotes, `<details>`/`<summary>`, `<table>`, `<tg-collage>`, `<tg-slideshow>`, `<tg-map>`, `<tg-math-block>`, `<tg-thinking>`, `<img>`/`<video>`/`<audio>`, `<a name>`/`<a href="#…">`, `<cite>`, and the classic `<b>`/`<i>`/`<u>`/`<s>`/`<code>`/`<tg-spoiler>`/`<tg-emoji>`/`tg://user?id=…` set). `url`/`email_address`/`phone_number`/`bank_card_number`/`@mention`/`#hashtag`/`$cashtag`/`/bot_command` need **no explicit tag at all** — telegram auto-detects them from plain text unless you pass `skipEntityDetection: true`.
+most tags are **confirmed** directly from telegram's schema (`<p>`, `<h1>`–`<h6>`, `<pre><code>`, `<hr/>`, `<footer>`, `<blockquote>`, `<aside>` for pull-quotes, `<details>`/`<summary>`, `<table>`, `<tg-collage>`, `<tg-slideshow>`, `<tg-map>`, `<tg-math-block>`, `<tg-thinking>`, `<img>`/`<video>`/`<audio>`, `<a name>`/`<a href="#…">`, `<cite>`, and the classic `<b>`/`<i>`/`<u>`/`<s>`/`<code>`/`<tg-spoiler>`/`<tg-emoji>`/`tg://user?id=…` set). `url`/`email_address`/`phone_number`/`bank_card_number`/`@mention`/`#hashtag`/`$cashtag`/`/bot_command` need **no explicit tag at all** — telegram auto-detects them from plain text unless you pass `.noEntityDetection()`.
 
-a handful of inline/block features have **no documented tag** in the schema at all (`marked`, `subscript`, `superscript`, `date_time`, inline `mathematical_expression`, `reference`/`reference_link`, table `is_bordered`/`is_striped`). those are implemented as a best-effort guess (standard html5 tags where one exists, a `tg-*`-style name otherwise) and flagged in their doc comments in `inline.ts`/`blocks.ts` — verify against the live "rich message formatting options" docs before relying on the exact spelling in production.
+a handful of inline/block features have **no documented tag** in the schema at all (`marked`, `subscript`, `superscript`, `date_time`, inline `mathematical_expression`, `reference`/`reference_link`, table `is_bordered`/`is_striped`). those are implemented as a best-effort guess (standard html5 tags where one exists, a `tg-*`-style name otherwise) and flagged in their doc comments in `inline.ts`/`blocks.ts` — verify against the live "rich message formatting options" docs before relying on the exact spelling in production. where rich-markdown has no native token for a block at all (`footer`, pull-quote, collage/slideshow, map, `details`, `underline`, `subscript`, `superscript`), the raw html tag is embedded as-is in the markdown output too — telegram's markdown parser accepts embedded html blocks as long as they're blank-line-separated, which the block builders already handle.
 
 `sendRichMessage` has no `attach://`/multipart upload path (unlike `sendPhoto`) — media blocks (`image`/`video`/`audio`) take a hosted url, not a local file.
 
+### tables and lists carry their full field set
+
+`cell()` and `item()` aren't afterthoughts bolted onto a plain-array api — they're first-class `RichNode`s that also carry the options `table()`/`list()` need to do the right thing per dialect:
+
+```ts
+table(
+  [
+    [cell("day", { header: true }), cell("count", { header: true, align: "right" })],
+    [cell("mon"), cell(128, { align: "right", colspan: 2 })],
+  ],
+  { bordered: true, caption: "week" },
+);
+```
+
+in html this is a full `<table>` with `colspan`/`rowspan`/`valign`/per-cell `<th>`/`<td>`; in markdown it degrades gracefully to a gfm table (structurally header-first, alignment preserved, the rest dropped — gfm has no cell spans). `list()` accepts bare values directly (auto-wrapped in a plain item) or explicit `item()`s for checkboxes and ordered-list numbering overrides (`value`, `type`) — no separate wrapper step required either way.
+
 ## api
 
-| export                                                                                                 | what                                                                      |
-|:-------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------|
-| `html`                                                                                                 | tagged template for the extended-html dialect, auto-escaped interpolation |
-| `bold`/`italic`/`underline`/`strikethrough`/`spoiler`/`code`/`marked`/`subscript`/`superscript`        | inline marks                                                              |
-| `link`/`textMention`/`anchor`/`anchorLink`/`customEmoji`/`dateTime`/`math`/`reference`/`referenceLink` | inline nodes with data                                                    |
-| `paragraph`/`heading`/`preformatted`/`footer`/`divider`/`mathBlock`/`anchorBlock`                      | simple blocks                                                             |
-| `blockquote`/`pullquote`/`details`/`list`/`item`/`table`/`cell`                                        | structural blocks                                                         |
-| `collage`/`slideshow`/`map`/`image`/`video`/`audio`/`thinking`                                         | media & draft-only blocks                                                 |
-| `document`/`markdown`                                                                                  | assemble blocks into an `InputRichMessage`                                |
-| `sendRichMessage`/`sendRichMessageDraft`                                                               | standalone send functions, no plugin required                             |
-| `rich()`                                                                                               | plugin: adds `ctx.sendRichMessage`/`ctx.richMessageDraft`                 |
-| `RichMessageDraft`                                                                                     | the draft/streaming session class                                         |
-| `isParagraph`, `isTable`, `isCustomEmoji`, …                                                           | one type guard per `RichBlock`/`RichText` variant                         |
-| `richTextToPlainText`/`richBlockToPlainText`/`richMessageToPlainText`                                  | flatten to plain text                                                     |
+| export                                                                                                 | what                                                                                     |
+|:-------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------|
+| `html` / `md`                                                                                          | tagged templates — same builders, either dialect, auto-escaped interpolation             |
+| `document`                                                                                             | options-object form: assemble blocks into a `RichDocument` with an explicit dialect      |
+| `RichDocument`                                                                                         | the sendable result — `.rtl()`/`.noEntityDetection()`, `toInputRichMessage()`/`toJSON()` |
+| `bold`/`italic`/`underline`/`strikethrough`/`spoiler`/`code`/`marked`/`subscript`/`superscript`/`br`   | inline marks                                                                             |
+| `link`/`textMention`/`anchor`/`anchorLink`/`customEmoji`/`dateTime`/`math`/`reference`/`referenceLink` | inline nodes with data                                                                   |
+| `paragraph`/`heading`/`h1`–`h6`/`preformatted`/`footer`/`divider`/`mathBlock`/`anchorBlock`            | simple blocks                                                                            |
+| `blockquote`/`pullquote`/`details`/`list`/`item`/`table`/`cell`/`join`                                 | structural blocks & composition                                                          |
+| `collage`/`slideshow`/`map`/`image`/`video`/`audio`/`thinking`                                         | media & draft-only blocks                                                                |
+| `RichNode`/`isRichNode`/`makeNode`/`Dialect`/`Level`/`RichError`                                       | the node contract, for writing your own dual-dialect builder                             |
+| `escapeMarkdown`/`escapeMarkdownUrl`                                                                   | the raw markdown escapers the builders use internally                                    |
+| `sendRichMessage`/`sendRichMessageDraft`                                                               | standalone send functions, no plugin required                                            |
+| `rich()`                                                                                               | plugin: adds `ctx.sendRichMessage`/`ctx.richMessageDraft`                                |
+| `RichMessageDraft`                                                                                     | the draft/streaming session class — `rewrite()`/`write()`/`send()`/`cancel()`            |
+| `isParagraph`, `isTable`, `isCustomEmoji`, …                                                           | one type guard per `RichBlock`/`RichText` variant                                        |
+| `richTextToPlainText`/`richBlockToPlainText`/`richMessageToPlainText`                                  | flatten to plain text                                                                    |
 
 plus the full generated type surface (`RichMessage`, `RichBlock`, `RichText`, and every `RichBlock*`/`RichText*` interface) re-exported from `@yaebal/types` for convenience.
 

package/lib/blocks.d.ts

@@ -1,75 +1,128 @@
-import { type Insertable, type RichNode } from "./inline.js";
+import { type RichNode } from "./node.js";
+import { type Insertable } from "./render.js";
 /** a caption + optional credit for a media/collage/slideshow/map block (`RichBlockCaption`). */
 export interface Caption {
     caption?: Insertable;
     /** `RichBlockCaption.credit`, confirmed `<cite>`. */
     credit?: Insertable;
 }
-/** `RichBlockParagraph`, `<p>`. */
-export declare function paragraph(...children: Insertable[]): RichNode;
-/** `RichBlockSectionHeading`, `<h1>`–`<h6>`. `level` is telegram's `size` (1 largest, 6 smallest). */
-export declare function heading(level: 1 | 2 | 3 | 4 | 5 | 6, ...children: Insertable[]): RichNode;
-/** `RichBlockPreformatted`, nested `<pre><code>`, matching classic parse_mode html. */
+/** `RichBlockParagraph` — `<p>` in html, bare text in markdown (blocks are blank-line-joined). */
+export declare function paragraph(...items: Insertable[]): RichNode;
+/** `RichBlockSectionHeading` — `<h1>`–`<h6>` / `#`–`######`. `level` is telegram's `size` (1 largest). */
+export declare function heading(level: 1 | 2 | 3 | 4 | 5 | 6, ...items: Insertable[]): RichNode;
+/** `heading(1, …)`. */
+export declare const h1: (...items: Insertable[]) => RichNode;
+/** `heading(2, …)`. */
+export declare const h2: (...items: Insertable[]) => RichNode;
+/** `heading(3, …)`. */
+export declare const h3: (...items: Insertable[]) => RichNode;
+/** `heading(4, …)`. */
+export declare const h4: (...items: Insertable[]) => RichNode;
+/** `heading(5, …)`. */
+export declare const h5: (...items: Insertable[]) => RichNode;
+/** `heading(6, …)`. */
+export declare const h6: (...items: Insertable[]) => RichNode;
+/**
+ * `RichBlockPreformatted` — nested `<pre><code>` (matching classic parse_mode
+ * html) / a fenced code block. `text` is raw code: html-escaped in the html
+ * dialect, emitted verbatim inside the markdown fence.
+ */
 export declare function preformatted(text: string, language?: string): RichNode;
-/** `RichBlockFooter`, `<footer>`. */
-export declare function footer(...children: Insertable[]): RichNode;
-/** `RichBlockDivider`, `<hr/>`. */
+/** `RichBlockFooter` — `<footer>`; no markdown token, raw tag embedded there too. */
+export declare function footer(...items: Insertable[]): RichNode;
+/** `RichBlockDivider` — `<hr/>` / `---`. */
 export declare function divider(): RichNode;
-/** `RichBlockMathematicalExpression`, confirmed `<tg-math-block>` (LaTeX). */
+/** `RichBlockMathematicalExpression` — confirmed `<tg-math-block>` / `$$…$$` (raw LaTeX, unescaped in markdown). */
 export declare function mathBlock(expression: string): RichNode;
-/** `RichBlockAnchor`, `<a name="…">` at block level. */
+/** `RichBlockAnchor` — `<a name="…">` at block level, in both dialects. */
 export declare function anchorBlock(name: string): RichNode;
-/** `RichBlockBlockQuotation`, `<blockquote>`, with an optional `<cite>` credit. */
-export declare function blockquote(children: Insertable[], credit?: Insertable): RichNode;
-/** `RichBlockPullQuotation`, loosely `<aside>` per the schema, with an optional `<cite>` credit. */
+/**
+ * `RichBlockBlockQuotation` — `<blockquote>` with an optional `<cite>` credit;
+ * `>`-prefixed lines in markdown (each array item becomes its own line, the
+ * credit a trailing `> — credit` line).
+ */
+export declare function blockquote(items: Insertable[], credit?: Insertable): RichNode;
+/** `RichBlockPullQuotation` — loosely `<aside>` per the schema, with an optional `<cite>` credit. */
 export declare function pullquote(text: Insertable, credit?: Insertable): RichNode;
-/** `RichBlockCollage`, confirmed custom tag `<tg-collage>`. */
+/** `RichBlockCollage` — confirmed custom tag `<tg-collage>` (raw in markdown too). */
 export declare function collage(blocks: Insertable[], caption?: Caption): RichNode;
-/** `RichBlockSlideshow`, confirmed custom tag `<tg-slideshow>`. */
+/** `RichBlockSlideshow` — confirmed custom tag `<tg-slideshow>` (raw in markdown too). */
 export declare function slideshow(blocks: Insertable[], caption?: Caption): RichNode;
+declare const TABLE_CELL: unique symbol;
 export interface TableCellOptions {
+    /** `<th>` instead of `<td>`. html-only — gfm's header is structural (see `table`). */
     header?: boolean;
+    /** html-only — gfm has no cell spans. */
     colspan?: number;
+    /** html-only — gfm has no cell spans. */
     rowspan?: number;
-    /** default `"left"`, matching `RichBlockTableCell.align`. */
+    /** default `"left"`, matching `RichBlockTableCell.align`. feeds gfm's column alignment row. */
     align?: "left" | "center" | "right";
-    /** default `"top"`, matching `RichBlockTableCell.valign`. */
+    /** default `"top"`, matching `RichBlockTableCell.valign`. html-only. */
     valign?: "top" | "middle" | "bottom";
 }
+/** one table cell — a `RichNode` carrying its options so `table()` can read the gfm alignment. */
+export interface TableCell extends RichNode {
+    readonly [TABLE_CELL]: true;
+    readonly align?: "left" | "center" | "right";
+}
 /** one `<td>`/`<th>` cell; `content` omitted ⇒ an invisible cell (per `RichBlockTableCell`). */
-export declare function cell(content?: Insertable, options?: TableCellOptions): RichNode;
+export declare function cell(content?: Insertable, options?: TableCellOptions): TableCell;
 export interface TableOptions {
-    /** best-effort: rendered as the `border` attribute. */
+    /** best-effort: rendered as the `border` attribute. html-only. */
     bordered?: boolean;
-    /** best-effort: no standard html equivalent, rendered as `data-striped`. */
+    /** best-effort: no standard html equivalent, rendered as `data-striped`. html-only. */
     striped?: boolean;
+    /** `<caption>` in html; a leading caption line in markdown. */
     caption?: Insertable;
 }
-/** `RichBlockTable`, confirmed `<table>`. build rows with `cell()`. */
+/**
+ * `RichBlockTable`, confirmed `<table>` / a gfm table. build cells with `cell()`
+ * (a bare value is wrapped in a plain `cell()` automatically). gfm structurally
+ * requires a header row, so in markdown `rows[0]` always renders as the header
+ * line and `colspan`/`rowspan`/`valign`/`header`/`bordered`/`striped` are
+ * dropped; in html the header is per-cell opt-in (`cell(x, { header: true })`).
+ */
 export declare function table(rows: Insertable[][], options?: TableOptions): RichNode;
 export interface DetailsOptions {
     /** `RichBlockDetails.is_open` — content visible by default. defaults to `false`. */
     open?: boolean;
 }
-/** `RichBlockDetails`, confirmed `<details>`/`<summary>`. */
+/**
+ * `RichBlockDetails`, confirmed `<details>`/`<summary>` (an html-only tag, legal
+ * inside markdown too — there the body must be blank-line-separated or telegram
+ * renders it as literal text).
+ */
 export declare function details(summary: Insertable, blocks: Insertable[], options?: DetailsOptions): RichNode;
+declare const LIST_ITEM: unique symbol;
 export interface ListItemOptions {
     /** an unchecked/checked checkbox prefix (`RichBlockListItem.has_checkbox`/`is_checked`). */
     checkbox?: boolean;
     checked?: boolean;
-    /** ordered-list numeric override (`RichBlockListItem.value`) — standard `<li value>`. */
+    /** ordered-list numeric override (`RichBlockListItem.value`) — standard `<li value>`; restarts gfm numbering. */
     value?: number;
-    /** ordered-list label style override (`RichBlockListItem.type`) — standard `<li type>`. */
+    /** ordered-list label style override (`RichBlockListItem.type`) — standard `<li type>`. html-only. */
     type?: "a" | "A" | "i" | "I";
 }
-/** one `<li>` for `list()`. */
-export declare function item(blocks: Insertable[], options?: ListItemOptions): RichNode;
+/** one list item — a `RichNode` carrying its options so `list()` can number/prefix it. */
+export interface ListItem extends RichNode {
+    readonly [LIST_ITEM]: true;
+    readonly value?: number;
+}
+/** one `<li>` for `list()` — only needed when a plain value isn't enough (checkbox, value, type). */
+export declare function item(blocks: Insertable[], options?: ListItemOptions): ListItem;
 export interface ListOptions {
     /** `<ol>` instead of `<ul>`. defaults to `false`. */
     ordered?: boolean;
+    /** first number of an ordered list — standard `<ol start>` / the first gfm marker. */
+    start?: number;
 }
-/** `RichBlockList`, `<ul>`/`<ol>` of `item()`s. */
-export declare function list(items: Insertable[], options?: ListOptions): RichNode;
+/**
+ * `RichBlockList` — `<ul>`/`<ol>` / `- `/`1. ` lines. entries may be plain
+ * values (wrapped in a default `item()` automatically) or explicit `item()`s
+ * for checkboxes and numbering overrides.
+ */
+export declare function list(entries: Insertable[], options?: ListOptions): RichNode;
 export interface MapOptions {
     /** 13–20, per `RichBlockMap.zoom`. */
     zoom: number;
@@ -77,8 +130,9 @@ export interface MapOptions {
     height: number;
 }
 /**
- * `RichBlockMap`, confirmed custom tag `<tg-map>` — attribute names/encoding are a
- * best-effort guess (lat/long/zoom/width/height are telegram's own field names).
+ * `RichBlockMap`, confirmed custom tag `<tg-map>` (raw in markdown too) —
+ * attribute names/encoding are a best-effort guess (lat/long/zoom/width/height
+ * are telegram's own field names).
  */
 export declare function map(location: {
     latitude: number;
@@ -111,5 +165,12 @@ export declare function audio(src: string, options?: MediaOptions): RichNode;
  * schema states it can be used in `sendRichMessageDraft` payloads but is never
  * received back on a real message. see `RichMessageDraft` in draft.ts.
  */
-export declare function thinking(...children: Insertable[]): RichNode;
+export declare function thinking(...items: Insertable[]): RichNode;
+/**
+ * join content with a separator. if any entry is a block, the result is a block
+ * and entries are blank-line-joined (markdown) / concatenated (html) — the
+ * separator only applies to all-inline joins.
+ */
+export declare function join(entries: Insertable[], separator?: Insertable): RichNode;
+export {};
 //# sourceMappingURL=blocks.d.ts.map

package/lib/blocks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"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"}